Vuepress Reco主题备忘 |
您所在的位置：网站首页 › vue 侧边栏 显示 隐藏 › Vuepress Reco主题备忘 |
Vuepress Reco主题备忘
|
文章目录 0. 前言1. 感兴趣的功能1.1. 页面介绍1.2. Markdown 编辑功能1.3. Markdown Front Matter 功能1.4. 更多功能 2. 进一步配置备忘2.1. 配置文件相关2.2. 目录结构2.3. 静态资源2.4. 特殊页面 3. 其他问题3.1. 新项目构建流程3.2. 侧边栏使用问题3.3. 首页侧边栏隐藏的问题3.4. 评论插件 Vssue 的使用问题3.5. 手动创建侧边栏比较麻烦3.6. 文档模式下的标签（Tag）与分类（Categories）
0. 前言
VuePress文档：英文版，中文版 英文版的文档比中文版的新，但大多数内容中文版都有。 Reco主题官网 注意，Reco 主题知识 VuePress 官方默认主题的扩展，不是一个全新的主题。 概述 正如我在以前的博客里提到的，其实我对VuePress的印象很不好，主要原因在于，感觉VuePress的文档对于新手（前端小白）来说非常不友好。公平地说，在我硬着头皮研究了一段时间，对整体比较熟悉之后，感觉文档还是可以的。（看来，不同受众不同感受）。我其实比较烂，以前一直使用Hexo Next，现在研究VuePress的主要原因是： 自己的团队要输出一些文档，目前使用的是Gitbook。团队文档的主要需求是：能够快速实现评论功能，必须部署在内网（内网有搭建Gitlab）。寻找之后，发现Vusse插件能够通过Gitlab Issue来实现评论功能，而Vussue不支持Hexo、Doscify，单对于VuePress支持非常好。
1. 感兴趣的功能
1.1. 页面介绍
封面 来源：默认主题功能。其他：reco提供了一个博客主题的封面，没仔细研究过。 具体使用参考 文档 文档形式封面的参考配置以及效果如下
---
home: true
heroImage: /hero.png
heroText: Hero 标题
tagline: Hero 副标题
actionText: 快速上手 →
actionLink: /zh/guide/
features:
- title: 简洁至上details: 以 Markdown 为中心的项目结构，以最少的配置帮助你专注于写作。
- title: Vue驱动details: 享受 Vue + webpack 的开发体验，在 Markdown 中使用 Vue 组件，同时可以使用 Vue 来开发自定义主题。
- title: 高性能details: VuePress 为每个页面预渲染生成静态的 HTML，同时在页面被加载的时候，将作为 SPA 运行。
footer: MIT Licensed | Copyright © 2018-present Evan You
---
概念：即 Markdown 文件最开头使用 ---包裹起来的内容，定义了标题、分类、标签、发布时间等一系列功能。 默认主题相关 参考文档预定义参数：title/lang/description/layout/permalink/metaTitle/meta 除了前三个，其他没见过 默认主题参数：navbar/sidebar/prev/next/search/tags 前5个都是用来设置功能开启与否最后一个可以优化内置搜索，也可以生成Tags界面（reco功能）Reco 相关 参考文档相关参数：title/date/sidebar/categories/tags/keys/publish/sticky 好像没什么要多介绍的，都是顾名思义。sticky是置顶与否，keys是设置密码与否。 1.4. 更多功能 站内搜索 来源：默认主题自带功能。具体使用参考文档功能：站内搜索，可通过文档tags优化搜索结果。 评论 来源：reco集成插件Vssue功能：这是基本需求，想用内置的Vssue评论，即通过issue来保存评论内容Vssue官网需要注意的是，如果使用Gitlab，需要将所有文章链接都添加到 callback url 中……不显示评论通过在front matter中添加 isShowComments: false实现。 加密 来源：reco自带参考文档功能：全局加密（进入网站就需要输入密码，关闭标签后登录失效）、文章加密 最近更新时间 来源：默认主题自带功能，必须使用git管理。效果不清楚，需要使用以下试试。 在网页上生成Edit this page连接 来源：默认主题自带功能。功能：在页面中可直接进入对应的github/gitlab连接。 2. 进一步配置备忘 2.1. 配置文件相关 vuepress官方参考文档reco参考文档配置很多，没有一个个试过。TODO，都试一试。 2.2. 目录结构 参考文档根目录下包含一个文件夹与package.json文件 前者包含所有文档内容，一般名为docs，当然，可以改。一般里面有.vuepress和其他markdown页面。后者包含一些基础命令 目录位置（即基于docs的相对路径）与相对url的关系 Relatie PathPage Routing/README.md//guide/README.md/guide//config.md/config.html 2.3. 静态资源 参考文档作用：用来保存一些图片/js/css等，方便页面访问。文件都保存在 .vuepress/config.js中。 2.4. 特殊页面 时间轴 来源：reco附加功能。具体使用请参考文档。作用：生成一条时间线，展示发表论文的时间。该时间可自动生成。 标签与分类：0.x和1.x有不同 第一步都相同，在普通文档的Front Matter中添加categories和tags信息。第二步，一个是新生成页面，指定FrontMatter信息，另一个是直接在配置文件中固定在导航栏中的位置。 1.x文档o.x文档 采坑：使用1.x的方法时，如果config.js中nav的设置与blogConfig冲突（比如nav中定义了3个标签，blogConfig中配置的位置为1或2），那blogConfig中的配置无效。 3. 其他问题 3.1. 新项目构建流程为了方便自己以后使用，建了一个项目： vuepress-reco-demo 第一步：安装nodejs，并新建一个文件夹，比如 vuepress-reco-demo 第二步：构建基本项目目录 根目录下新建 package.json创建文件夹（名字随意），用于保存所有配置以及markdown文件。 该文件夹中，有一个 .vuepress文件夹，用于保存vuepress的配置以及插件的配置，这个看vuepress的文档。其他的目录就是用来放markdown文件的。第三步：通过命令行进入该文件夹，安装各种依赖 安装 vuepress： npm install -D vuepress安装主题 reco： npm install vuepress-theme-reco --save-dev安装相关插件 公式： npm install -D vuepress-plugin-mathjax图片缩放： npm install -D vuepress-plugin-medium-zoom支持 Markdown Task List： npm install markdown-it-task-lists -D 3.2. 侧边栏使用问题 Reco 主题修改了一些默认主题侧边栏的功能，具体的可以参考官方文档。大概总结下 reco 中的侧边栏： 左侧侧边栏是默认主题提供的，而不是reco提供的；右侧侧边栏是reco主题提供的。文章内章节标题的显示：默认主题中，左侧侧边栏可以显示；reco主题中，左侧侧边栏不会显示，右侧侧边栏会显示。右侧侧边栏只用来显示文章内小标题，即目录。 默认主题中，front matter 中 sidebar: auto 的功能是自动添加文章章节标题到左侧侧边栏。很显然，这个功能在reco中无效了。在front matter中添加 sidebar: false以及subSidebar: false，并不能隐藏侧边栏，原因未知。 3.3. 首页侧边栏隐藏的问题 由于上面提到过，sidebar: false以及subSidebar: false并不能隐藏侧边栏，那首页中也肯定有侧边栏……解决的思路： 首先，我觉得这应该是reco处理的问题，而不是用奇怪的方法解决这个问题……但现在作者可能没空处理，只要用一些奇怪的方法来解决。解决的思路是，使用vuepress提供的多个侧边栏。多个侧边栏提供的功能是：为不同的子目录提供不同的侧边栏内容。那只要首页与其他页面不在同一个子目录下，就能解决我们的问题。 具体实现： 在docs目录下再建一个文件夹，比如还叫 docs。将除了首页README.md之外的其他markdown文件都放到这个文件夹中。在建立自定义侧边栏的时候，使用多个侧边栏的格式，即 sidebar: {'/docs/': [...]} 3.4. 评论插件 Vssue 的使用问题Vssue 提供了通过issue保存评论的功能，支持 Github/Gitlab/Gitee 等多个平台。 Vssue是我使用vuepress的主要原因，reco对vssue的支持比较好。我们需要全部运行在内网中，所以评论系统最好就是基于我们内部Gitlab的Issue。实际使用中，除了Gitlab/Gitee的使用都存在同一个不可接受且无法处理的问题。 问题描述： Vssue的实现其实是依靠 Github/Gitlab 等平台提供的各种API来处理的。Vssue的登录方式，其实使用了各平台的OAuth2功能。Vssue中的理想的认证流程大概是： 第一步：在某页的评论栏中点击选择登录。第二步：跳转到Github/Gitlab网站，访问OAuth2接口，实现认证。第三步：跳转返回第一步中的网页。 在设置跳转返回的url，需要在Github/Gitlab的OAuth2的应用中手动设置： 在Github中叫做 Authorization callback URL，支持设置的url以及所有子路径。在Gitlab中叫做 redirect uri，只支持设置的url。 换句话说，当使用Gitlab的时候，如果某个页面的url并没有手动添加到redirect uri中，那在这个页面就不能进行OAuth2认证（即不能进行登录操作，但如果之前已经登录了，只是要评论，还是能做到的）。这个问题已经在多个地方提到了 issue#58Vssue官方文档-支持的代码托管平台解决方案一：最笨的办法 将每个url都手动添加到redirect uri中。先写个脚本获取所有url，手动复制一下。如果文件增加速率不高，一周搞一次，也差不多了……解决方案二 - 自动跳转 目前 Vssue 已有相关PR，但作者还未处理，给Vssue开发者发了个邮件，希望大佬有空能处理下。首先问一个问题，为什么Gitlab/Gitee会这么设计 redirect uri 呢？我猜是安全问题……解决思路：将原页面url作为OAuth2的一个参数，所有OAuth2认证都跳转到同一个callback url，当OAuth2认证结束进入callback url后，在callback url页面通过保留的原页面url进行跳转。菜鸡的临时解决方法 直接修改vuepress项目中的 node_modules/@vssue/api-gitlab-v4/lib/index.js文件。修改内容从PR#101中找，大概就是修改了redirectAuth和handleAuth两个函数。 3.5. 手动创建侧边栏比较麻烦 问题描述：为了在侧边栏中显示新添加的文章，需要在每次添加文章后，手动修改config.js文件。 如果只是一个人开发，那还好。虽然麻烦，但至少自己捣鼓的配置文件，也知道怎么处理。如果多人开发，那就要求每个人都懂的这个内容，比较麻烦。有一个ISSUE对应本问题，虽然close了，但其实并没有解决…… 解决方案一 - 插件1自动生成 使用 vuepress-plugin-auto-sidebar 插件，可自动生成左侧侧边栏。但存在一个问题：这个插件只能生成同一个文件夹中所有文件的侧边栏，不能生成多个文件夹的内容。原因是可以从 ISSUE#13中找到，作者认为：如果以增加子文件夹来划分那就产生了新的问题：不同的目录在多少深度（几层子文件夹）时才划分为分组，配置起来感觉也并不直观。 这一块如果很多可以考虑下 官网 nav 的分组功能。 解决方案二 - 插件2自动生成 使用 vuepress-bar 插件，可自动生成侧边栏以及导航栏。不生成导航栏只生成侧边栏的方法运行成功，但存在首页侧边栏无法隐藏的问题。导航栏、侧边栏同时生成的方法运行不成功，但就算成功，应该也存在首页侧边栏无法隐藏的问题。解决方法三 - 直接添加js代码 ISSUE#13里面提到的方法，来源于这里。大概原理就是，获取某个文件夹内的所有md文件，作为children的内容。不能处理多级目录的问题。不用安装插件，如果不需要多级目录，这是一个好办法。最好的办法还是自己会写js代码……而我不想花时间 3.6. 文档模式下的标签（Tag）与分类（Categories）个人觉得，文档模式的默认配置下，两者的功能几乎一样。 两者都有的功能： 都能自动生成特殊页面。两者都只能进行一级分类，不能实现多级分类。标签有、分类没有的功能： 在每篇文章中，显示标签类别（不会显示分类类别）标签没有、分类有的功能： 导航栏中，分类标签有子分类的下拉菜单，标签没有下拉菜单。 |
【本文地址】
今日新闻 |
推荐新闻 |